<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no" />
<base href="../" />

<!-- oktavia -->
<link rel="stylesheet" href="assets/searchstyle.css" type="text/css" />
<script src="search/jquery-1.9.1.min.js"></script>
<script src="search/oktavia-jquery-ui.js"></script>
<script src="search/oktavia-english-search.js"></script>
<!-- /oktavia -->

<link rel="stylesheet" href="assets/style.css" type="text/css" />

<title>File Directives - Configure - H2O - the optimized HTTP/2 server</title>
</head>
<body>
<div id="body">
<div id="top">

<h1>
<a href="index.html">H2O</a>
</h1>
<p class="description">the optimized HTTP/1.x, HTTP/2 server</p>

<!-- oktavia -->
<form id="searchform">
<input class="search" type="search" name="search" id="search" results="5" value="" placeholder="Search" />
<div id="searchresult_box">
<div id="close_search_box">&times;</div>
<div id="searchresult_summary"></div>
<div id="searchresult"></div>
<div id="searchresult_nav"></div>
<span class="pr">Powered by <a href="https://github.com/shibukawa/oktavia">Oktavia</a></span>
</div>
</form>
<!-- /oktavia -->

</div>

<table id="menu">
<tr>
<td><a href="index.html">Top</a></td>
<td><a href="install.html">Install</a></td>
<td class="selected"><a href="configure.html">Configure</a></td>
<td><a href="faq.html">FAQ</a></td>
<td><a href="http://blog.kazuhooku.com/search/label/H2O" target="_blank">Blog</a></td>
<td><a href="http://github.com/h2o/h2o/" target="_blank">Source</a></td>
</tr>
</table>

<div id="main">

<h2>
<a href="configure.html">Configure</a> &gt;
File Directives
</h2>


<p>
This document describes the configuration directives of the file handler - a handler that for serving static files.
</p>
<p>
Two directives: <a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> and <a href="configure/file_directives.html#file.file"><code>file.file</code></a> are used to define the mapping.
Other directives modify the behavior of the mappings defined by the two.
</p>

<ul>
<li><a href="configure/file_directives.html#file.custom-handler">
<code>file.custom-handler</code>
</a></li>
<li><a href="configure/file_directives.html#file.dir">
<code>file.dir</code>
</a></li>
<li><a href="configure/file_directives.html#file.dirlisting">
<code>file.dirlisting</code>
</a></li>
<li><a href="configure/file_directives.html#file.etag">
<code>file.etag</code>
</a></li>
<li><a href="configure/file_directives.html#file.file">
<code>file.file</code>
</a></li>
<li><a href="configure/file_directives.html#file.index">
<code>file.index</code>
</a></li>
<li><a href="configure/file_directives.html#file.mime.addtypes">
<code>file.mime.addtypes</code>
</a></li>
<li><a href="configure/file_directives.html#file.mime.removetypes">
<code>file.mime.removetypes</code>
</a></li>
<li><a href="configure/file_directives.html#file.mime.setdefaulttype">
<code>file.mime.setdefaulttype</code>
</a></li>
<li><a href="configure/file_directives.html#file.mime.settypes">
<code>file.mime.settypes</code>
</a></li>
<li><a href="configure/file_directives.html#file.send-compressed">
<code>file.send-compressed</code>
</a></li>
<li><a href="configure/file_directives.html#file.send-gzip">
<code>file.send-gzip</code>
</a></li>
</ul>


<div id="file.custom-handler" class="directive-head">
<h3><a href="configure/file_directives.html#file.custom-handler"><code>"file.custom-handler"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
The directive maps extensions to a custom handler (e.g. FastCGI).
</p>

<p>
The directive accepts a mapping containing configuration directives that can be used at the <code>extension</code> level, together with a property named <code>extension</code> specifying a extension (starting with <code>.</code>) or a sequence of extensions to which the directives should be applied.
If all the files (including those without extensions) shall be mapped, this property must be set to <code>default</code>. 
Only one handler must exist within the directives.
</p>
<div class="example">
<div class="caption">Example. Mapping PHP files to FastCGI</div>
<pre><code>file.custom-handler:
  extension: .php
  fastcgi.connect:
    port: /tmp/fcgi.sock
    type: unix

</code></pre>
</div>


</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
</dl>

<div id="file.dir" class="directive-head">
<h3><a href="configure/file_directives.html#file.dir"><code>"file.dir"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
The directive specifies the directory under which should be served for the corresponding path.
</p>

<div class="example">
<div class="caption">Example. Serving files under different paths</div>
<pre><code>paths:
    &quot;/&quot;:
        file.dir: /path/to/doc-root
    &quot;/icons&quot;:
        file.dir: /path/to/icons-dir
</code></pre>
</div>


</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>path</dd>
<dt>See also:</dt>
<dd><a href="configure/file_directives.html#file.dirlisting"><code>file.dirlisting</code></a>,
<a href="configure/file_directives.html#file.file"><code>file.file</code></a>,
<a href="configure/file_directives.html#file.index"><code>file.index</code></a>
</dd>
</dl>

<div id="file.dirlisting" class="directive-head">
<h3><a href="configure/file_directives.html#file.dirlisting"><code>"file.dirlisting"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A boolean flag (<code>OFF</code>, or <code>ON</code>) specifying whether or not to send the directory listing in case none of the index files exist.

</p>

</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
<dt>Default:</dt>
<dd><code><pre>file.dirlisting: OFF</pre></code>
<dt>See also:</dt>
<dd><a href="configure/file_directives.html#file.dir"><code>file.dir</code></a>
</dd>
</dl>
<div id="file.etag" class="directive-head">
<h3><a href="configure/file_directives.html#file.etag"><code>"file.etag"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A boolean flag (<code>OFF</code>, or <code>ON</code>) specifying whether or not to send etags.

</p>

</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
<dt>Default:</dt>
<dd><code><pre>file.etag: ON</pre></code>
</dl>


<div id="file.file" class="directive-head">
<div class="directive-since">since v2.0</div>
<h3><a href="configure/file_directives.html#file.file"><code>"file.file"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
The directive maps a path to a specific file.
</p>

<div class="example">
<div class="caption">Example. Mapping a path to a specific file</div>
<pre><code>paths:
  /robots.txt:
    file.file: /path/to/robots.txt
</code></pre>
</div>


</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>path</dd>
<dt>See also:</dt>
<dd><a href="configure/file_directives.html#file.dir"><code>file.dir</code></a>
</dd>
</dl>

<div id="file.index" class="directive-head">
<h3><a href="configure/file_directives.html#file.index"><code>"file.index"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Specifies the names of the files that should be served when the client sends a request against the directory.
</p>

<p>
The sequence of filenames are searched from left to right, and the first file that existed is sent to the client.
</p>

</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
<dt>Default:</dt>
<dd><code><pre>file.index: [ &#39;index.html&#39;, &#39;index.htm&#39;, &#39;index.txt&#39; ]</pre></code>
<dt>See also:</dt>
<dd><a href="configure/file_directives.html#file.dir"><code>file.dir</code></a>
</dd>
</dl>

<div id="file.mime.addtypes" class="directive-head">
<h3><a href="configure/file_directives.html#file.mime.addtypes"><code>"file.mime.addtypes"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
The directive modifies the MIME mappings by adding the specified MIME type mappings.
</p>

<div class="example">
<div class="caption">Example. Adding MIME mappings</div>
<pre><code>file.mime.addtypes:
    &quot;application/javascript&quot;: &quot;.js&quot;
    &quot;image/jpeg&quot;: [ &quot;.jpg&quot;, &quot;.jpeg&quot; ]
</code></pre>
</div>

<p>
The default mappings is hard-coded in <a href="https://github.com/h2o/h2o/blob/master/lib/handler/mimemap/defaults.c.h">lib/handler/mimemap/defaults.c.h</a>.
</p>
<p>
It is also possible to set certain attributes for a MIME type.
The example below maps <code>.css</code> files to <code>text/css</code> type, setting <code>is_compressible</code> flag to <code>ON</code> and <code>priority</code> to highest.
</p>

<div class="example">
<div class="caption">Example. Setting MIME attributes</div>
<pre><code>file.mime.settypes:
    &quot;text/css&quot;:
         extensions: [&quot;.css&quot;]
         is_compressible: yes
         priority: highest
</code></pre>
</div>


<p>
Following attributes are recognized.
</p>

<table>
<tr><th>Attribute<th>Possible Values<th>Description
<tr><td><code>is_compressible</code><td><code>ON</code>, <code>OFF</code><td>if content is compressible
<tr><td><code>priority</code><td><code>highest<code>, <code>normal</code><td>send priority of the content
</table>

<p>
The <code>priority</code> attribute affects how the HTTP/2 protocol implementation handles the request.
For detail, please refer to the HTTP/2 directives listed in the <i>see also</i> section below.
By default, mime-types for CSS and JavaScript files are the only ones that are given <code>highest</code> priority.
</p>


</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
<dt>See also:</dt>
<dd><a href="configure/compress_directives.html#compress"><code>compress</code></a>,
<a href="configure/http2_directives.html#http2-casper"><code>http2-casper</code></a>,
<a href="configure/http2_directives.html#http2-reprioritize-blocking-assets"><code>http2-reprioritize-blocking-assets</code></a>
</dd>
</dl>

<div id="file.mime.removetypes" class="directive-head">
<h3><a href="configure/file_directives.html#file.mime.removetypes"><code>"file.mime.removetypes"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Removes the MIME mappings for specified extensions supplied as a sequence of extensions.
</p>

<div class="example">
<div class="caption">Example. Removing MIME mappings</div>
<pre><code>file.mime.removetypes: [ &quot;.jpg&quot;, &quot;.jpeg&quot; ]
</code></pre>
</div>


</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
</dl>

<div id="file.mime.setdefaulttype" class="directive-head">
<h3><a href="configure/file_directives.html#file.mime.setdefaulttype"><code>"file.mime.setdefaulttype"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Sets the default MIME-type that is used when an extension does not exist in the MIME mappings
</p>

</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
<dt>Default:</dt>
<dd><code><pre>file.mime.setdefaulttype: &quot;application/octet-stream&quot;</pre></code>
</dl>


<div id="file.mime.settypes" class="directive-head">
<h3><a href="configure/file_directives.html#file.mime.settypes"><code>"file.mime.settypes"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Resets the MIME mappings to given mapping.
</p>

<div class="example">
<div class="caption">Example. Resetting the MIME mappings to minimum</div>
<pre><code>file.mime.settypes:
    &quot;text/html&quot;:  [ &quot;.html&quot;, &quot;.htm&quot; ]
    &quot;text/plain&quot;: &quot;.txt&quot;
</code></pre>
</div>


</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
</dl>

<div id="file.send-compressed" class="directive-head">
<div class="directive-since">since v2.0</div>
<h3><a href="configure/file_directives.html#file.send-compressed"><code>"file.send-compressed"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A flag indicating how a pre-compressed file should be served.

</p>

<p>
If set to <code>ON</code>, the handler looks for a file with <code>.br</code> or <code>.gz</code> appended and sends the file, if the client is capable of transparently decoding a <a href="https://datatracker.ietf.org/doc/draft-alakuijala-brotli/">brotli</a> or <a href="https://tools.ietf.org/html/rfc1952">gzip</a>-encoded response.
For example, if a client requests a file named <code>index.html</code> with <code>Accept-Encoding: gzip</code> header and if <code>index.html.gz</code> exists, the <code>.gz</code> file is sent as a response together with a <code>Content-Encoding: gzip</code> response header.
</p>
<p>
If set to <code>OFF</code>, the handler always serves the file specified by the client.
</p>
<p>
Starting from version 2.2, <code>gunzip</code> is also supported.
If set, the handler acts identical to when the value was set to <code>ON</code>.
In addition, the handler will send an uncompressed response by dynamically decompressing the <code>.gz</code> file if the client and the server failed to agree on using a pre-compressed file as the response and if a non-compressed file was not found.
The option is useful when conserving disk space is important; it is possible to remove the uncompressed files in place for gzipped ones.
</p>

</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
<dt>Default:</dt>
<dd><code><pre>file.send-compressed: OFF</pre></code>
<dt>See also:</dt>
<dd><a href="configure/compress_directives.html#compress"><code>compress</code></a>
</dd>
</dl>

<div id="file.send-gzip" class="directive-head">
<h3><a href="configure/file_directives.html#file.send-gzip"><code>"file.send-gzip"</code></a></h3>
</div>

<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Obsoleted in 2.0.
Synonym of <a href="configure/file_directives.html#file.send-compressed"><code>file.send-compressed</code></a>.

</p>

</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path</dd>
</dl>







</div>
<div id="footer">
<p>
Copyright &copy; 2015-2020 <a href="http://dena.com/intl/">DeNA Co., Ltd.</a> et al.
</p>
</div>
</body>
</html>
